\documentclass[a4paper,10pt]{article}
\usepackage{listings}

\lstset{language=Java}
\lstset{breaklines=true, numbers=left}
% \lstset{basicstyle=\ttfamily}

\newcommand{\src}[1]{\lstinline[basicstyle=\ttfamily]|#1|}
\newcommand{\until}[1]{\textbf{Note (until #1): }}
\newcommand{\since}[1]{\textbf{Note (since #1): }}

%opening
\title{DockingFrames 1.0.6 - Common}
\author{Benjamin Sigg}

\begin{document}

\maketitle
\tableofcontents
\newpage

\begin{abstract}
The Common-project is a layer above DockingFrames. It allows to write applications using DF without the need to understand DF. Common does not add new features to DF, Common only combines existing code and reorganizes DF in a way that is easy to use.
\end{abstract}

\section{Introduction}
\subsection{DockingFrames}
What is DF? DF is an open source framework written in Java. It extends Java/Swing with the abbility of "dockable frames". Each frame contains some content, a \src{JTree} showing a directory or a \src{Table} showing the results of some game. Each frame has a title and some buttons (like a close-button). The user can move around these frames, the frames will align themself such that there is no unused space between them. DF provides many possibilities how frames can be combined to create a new layout.

\section{Common basics}
The Common project is divided in three packages. "Facile" contains some lonly classes which can be used to create minor effects. "Support" contains elements which are not even connected to DF, but still usefull.

The most interesting package however is "common". "Common" contains the layer that will enable you to rapidly write applications using DF. This first section deals with the basic features of Common.

\subsection{Basic elements}
In the understanding of Common, an ordinary application has one \src{JFrame}, which is called the "mainframe", showing the content of the application. The content is painted through some \src{JComponent}s called "panels". Each panel represents some view of the content, for example a texteditor might have one panel for each open document.

Common stands between mainframe and the panels, separating them, and allowing the user to move then panels around.

To do so, each panel gets wrapped into a \src{CDockable}, such a combination is simply called "dockable". Dockables are then put onto a \src{CContentArea} which is just a child of the mainframe.

Since there is a complex mechanism between the dockables, a control unit is needed. The control unit is provided by the \src{CControl}, or just the "controller".

\subsection{Creating the controller}
The first thing that needs to be done before using Common is to set up the controller. This is done by creating a new object of type \src{CControl}:
\begin{lstlisting}
JFrame frame = new JFrame( "Main-Frame" );
boolean secure = false;
CControl control = new CControl( frame, secure );
\end{lstlisting}

Let's have a brief look at the code. Clearly in line \src{1} the mainframe of the application is created. The controller needs to know the mainframe, it is used as parent of \src{Window}s which are opened for example when dragging a dockable.

In line \src{2} it is specified that the application does run in an unsecure environment. An unsecure environment is normal for applications. An applet or a webstart-application would run in a secure environment. The controller needs to know that either it  can use non-secure optimations (like globally observing all \src{AWT-Events}) or has to use inefficient workarounds.

Finally in line \src{3} the controller is created.

\subsection{Between mainframe and dockable}
After creating mainframe and controller, the layer between mainframe and the dockables has to be set up.

\subsubsection{Content area}
A \src{CContentArea} contains all the functionality an application normally needs. The controller grants access to a default-content-area through \\\src{CControl.getContentArea()}. You can use \src{CControl.createContentArea(String)} to create additional areas when needed.
\begin{lstlisting}
JFrame frame = ...
CControl control = ...	
frame.add( control.getContentArea() );
\end{lstlisting}
Note line \src{3}, a content-area is just a \src{JComponent} and can be added anywhere.

\subsubsection{Stations}
Sometimes a \src{CContentArea} is too much or does not the right thing. In version 1.0.4 the \src{CStation} was introduced. A \src{CStation} is a thin wrapper around an ordinary \src{DockStation}. Clients can write their own \src{CStation}s or use some of the predefined stations:
\begin{description}
 \item[CMinimizeArea] A station where minimized dockables are shown.
 \item[CGridArea] A station where normalized and maximized dockables are shown.
 \end{description}

An example setting up a layout where normalized dockables can be shown in the middle of a \src{JFrame}, and minimized dockables are shown at the bottom only:
\begin{lstlisting}
JFrame frame = new JFrame( "Demo" );
CControl control = new CControl( frame );

CMinimizeArea miniArea = new CMinimizeArea( control, "mini" );
miniArea.setDirection( FlapDockStation.Direction.NORTH );
control.add( miniArea, true );

CGridArea gridArea = control.createGridArea( "grid" );

frame.add( gridArea.getComponent(), BorderLayout.CENTER );
frame.add( miniArea, BorderLayout.SOUTH );
\end{lstlisting}
Note how \src{miniArea}, defined in line \src{4}, has to be added to the control in line \src{6}. The argument \src{true} tells the control, that \src{miniArea} is a root station, which means that \src{miniArea} has no parent.

A second station called \src{gridArea} is created in line \src{8}. Here one of the factory methods of \src{CControl} is used. That method does all the wiring that is necessary, and factory methods should be preferred whenever possible.

\subsection{Wrapping a panel}
There are some thoughts needed to create a dockable (to wrap a panel into a \src{CDockable}). Each kind of panel can fall in one of two categories: the number of instances during the lifetime of an application remains the same, or the number changes.

Those kinds of panels whose number does not change, should be wrapped into \src{SingleCDockable}s, the others in \src{MultipleCDockable}s. \src{SingleCDockable} and \src{MultipleCDockable} are only interfaces, for most developers the implementations \src{DefaultSingleCDockable} and \src{DefaultMultipleCDockable} will suffice. Only developers interested in writing elements which are parents of dockables need to write new classes and implement the interfaces.

Once a dockable is created, it has to be registered at the controller through the method \src{CControl.add}. Afterwards it can be made visible using \src{CDockable.setVisible}. Unless otherwise instructed, the controller will then open the dockable at a default location.

\subsubsection{Single dockables}
A single dockable is an object of type \src{SingleCDockable}. These dockables are created once by the application, added to the controller and made visible. Then they remain in the memory until they are explicitly removed from the controller, or the application terminates.

Every single dockable needs a unique identifier. This identifier allows the controller to store information about a dockable persistently and later to find the information again.

An example for a single dockable would be the list of documents that are currently open in a text editor.
\begin{lstlisting}
CControl control = ...
SingleCDockable documents = 
	new DocumentList( "myapp-document-id" );
control.add( documents );
documents.setVisible( true );
\end{lstlisting}

\subsubsection{Multiple dockables}
A multiple dockable is an object of type \src{MultipleCDockable}. These dockables are created by the application or the controller, shown for some time and then removed from memory. Unlike a single dockable, a multiple dockable can be created or deleted at any time.

Every multiple dockable needs a \src{MultipleCDockableFactory}, which must have been registered at the controller.

Example: the documents of a text editor
\begin{lstlisting}
CControl control = ...
MultipleCDockableFactory factory = new DocumentDockableFactory();
control.add( "myapp-document-factory-id", factory );

MultipleCDockable document = new DocumentDockable( factory, "/home/beni/Desktop/file.txt" );
control.add( document );
document.setVisible( true );
\end{lstlisting}

\subsection{Grouping dockables}
Every time the user loads a previously stored layout, the multiple dockables will be deleted and new instances created. That can be very annoying and disturbing for user and developer. "working-areas" are designed to prevent such a behavior. Every \src{CStation} whose method \src{isWorkingArea} returns \src{true} is considered to be a working area. Most clients will use the class \src{CWorkingArea} and so this chapter will from now on use working-area and \src{CWorkingArea} as synonym.

\src{CWorkingArea}s can be fetched from the controller using \ \src{CController.createWorkingArea}. After their creation they are handled like every other single dockable, except that the \src{createWorkingArea}-method already added them to the controller.

Every dockable which should sit on a \src{CWorkingArea} needs to be put there. The most convenient way is to use \src{CDockable.setWorkingArea}. The controller will store this property when storing the layout. Have a look at the example:
\begin{lstlisting}
CControl control = ...
CWorkingArea area = control.createWorkingArea( "area" );
SingleCDockable dockable = new ...

area.setSuppressTitle( false );
area.setTitleText( "Some title" );

area.setVisible( true );

control.add( dockable );
dockable.setWorkingArea( area );
dockable.setVisible( true );
\end{lstlisting}
An analysis: in line \src{2} a new \src{CWorkingArea} is created. Then in lines \src{5,6} the decorations of \src{area} are activated and the title set. In line \src{8} \src{area} is made visible. In line \src{10} a new dockable is added to the structure, and its preferred parent is set in line \src{11}. Afterwards \src{dockable} is made visible as well.

\subsection{Changing the mode of a dockable}
Every dockable needs to be in one mode: minimized, normalized, maximized or externalized. The user can change the mode of a dockable by clicking some buttons or moving the dockable around. Clients can read or change this mode as well, they just call \src{CDockable.getExtendedMode()} or \src{CDockable.setExtendedMode}.

The client can also specifiy, what modes are available for a dockable. When using the default-\src{CDockable}s, then \src{setMinimizable}, \src{setMaximizable} and \\\src{setExternalizable} can be used.

\subsection{Close a dockable}
When a dockable is no longer of use, it needs to be removed. There are several ways to remove a dockable and they have different effects.

With \src{CDockable.setVisible} the visibility of a dockable can just be changed to \src{false}. Single dockables will remain in the structure and can be reopened at a later time. \src{MultipleCDockable}s will be removed from the controller unless the \src{removeOnClose} property was set to \src{false}. When using a \\\src{DefaultMultipleCDockable} then this property can be changed through \\\src{setRemoveOnClose}.

With \src{CControl.remove} the dockable is not only made invisible, it is also removed from the controller. All properties related to the dockable will be lost. Unless added to a controller again, it is no longer possible to reopen the dockable.

Or give the user the possibility to close the dockable: setting the property \src{closeable} of the default-\src{CDockable}s to \src{true} will add a close-button to the title. A client can add a \src{CDockableStateListener} to the dockable in order to get informed when the visibility state changes. Clicking the close-button has the same effects as calling \src{setVisible(false)}.

After some time, the need for any elements of the framework might vanish. Using \src{CControl.destroy()} will release as many resources as possible.

\section{Common features}
There are more advanced features in Common. This section will introduce you to some methods allowing the fine-tuning of Commons.

\subsection{Actions}
Most dockables have some actions associated, for example a dockable showing some image might have the actions "zoom in" and "zoom out". Common provides a way to write such actions and attach their graphical representation (for example a button) to the titles of dockables. 

Actions are modeled by \src{CAction} and various subinterfaces. All default-\src{CDockable}s have methods to add or remove these actions.

In the source, that might look like this:
\begin{lstlisting}
DefaultSingleCDockable image = ...
CAction zoom = new ZoomAction();
image.addAction( zoom );
\end{lstlisting}

\subsubsection{CButton}
A \src{CButton} is just clicked by the user, and then executes some action. It is almost the same as a \src{JButton}. There is only one way to write a new \src{CButton}-action:

\begin{lstlisting}
public class MyActions extends CButton{
	public MyAction(){
		setText( "Action" );
	}

	public void action(){
		// do something
	}
}
\end{lstlisting}

\subsubsection{CCheckBox}
The \src{CCheckBox} is an action with two states: selected or not selected. The state changes every time the user triggers the action. It is almost a \src{JCheckBox}. Writing a new \src{CCheckBox} is similar to writing a new \src{CButton}, except that the method \src{changed()} instead of \src{action()} has to be overriden.

\subsubsection{CRadioButton}
A \src{CRadioButton} is the same as a \src{CCheckBox} with one big difference: several \src{CRadioButton}s can be grouped together, and only one button of the group can be selected. The currently selected button gets unselected whenever the user triggers another button. Grouping is done with the help of a \src{CRadioGroup}:
\begin{lstlisting}
CRadioButton buttonA = ...
CRadioButton buttonB = ...

CRadioGroup group = new CRadioGroup();
group.add( buttonA );
group.add( buttonB );
\end{lstlisting}

\subsubsection{CMenu}
A \src{CMenu} is a list of actions. When the user triggers the \src{CMenu}, a popup-menu will appear and show the contents of the \src{CMenu}.

\subsubsection{CDropDownButton}
Something similar to the \src{CMenu}, but more advanced. The \src{CDropDownButton} serves two purposes. It is a menu like \src{CMenu}, and it remembers which action was triggered last. Triggering the button will trigger that last action again.

An example:
\begin{lstlisting}
CDropDownButton dropDown = new CDropDownButton();

CButton buttonA = ...
CButton buttonB = ...

dropDown.add( buttonA );
dropDown.add( buttonB );

dropDown.setSelection( buttonA );

buttonB.setDropDownSelectable( false );
\end{lstlisting}
Let's analyze this code. In lines \src{1-4} some actions are created. In lines \src{6,7} the two \src{CButton}-actions are inserted into the menu of \src{dropDown}. Then in line \src{9} one action is marked as the last triggered action. \src{dropDown} will now show icon and text from \src{buttonA}. Something interesting happens in line \src{11}: the call to \src{setDropDownSelectable} will make sure that even when \src{buttonB} is triggered, it will not be marked as the last triggered action. Sometimes one wants to use \src{CDropDownButton} just as an ordinary drop-down-menu without more functionality.

\subsubsection{CBlank}
The action \src{CBlank} is never visible nor does the action anything. It can be used in places where a non-\src{null} action is required, but the developer does not want to show an action.

\subsubsection{Predefined actions}
There are a number of actions which are added automatically to a \src{CDockable}. For example the close-action or the maximize-action. These actions are often rooted deeply in the system and it is not possible to access them. However it is possible to override them. Every \src{CDockable} has a method \src{getAction} which is called before one of the predefined actions is shown. If that \src{getAction} method returns a value other than \src{null}, the predefined action gets replaced.

An example:
\begin{lstlisting}
DefaultSingleCDockable dockable = ...
dockable.setMaximizable( true );
dockable.putAction( CDockable.ACTION_KEY_MAXIMIZE, CBlank.BLANK );
\end{lstlisting}
This code produces a dockable that is clearly maximizable (line \src{2}). However when the programm is running, the maximize-action is not visible. That is because in line \src{3} the predefined action for maximizing gets overridden by a new action. Since the new action is a \src{CBlank}, the action gets in fact invisible.

This feature has to be treated very carefully. Every predefined action has a special meaning, however the replacing actions depend on the client only. The developer has to ensure, that the replacing actions do something meaningful.

\subsection{The location of dockables}
Naturally a dockable has some location. This section deals with the various forms of locations that are used in DF.

\subsubsection{for a single Dockable}
For one dockable alone, the location is represented through a \src{CLocation}. Calling \src{CDockable.getLocation()} gets the current location (if any) of a dockable, \src{CDockable.setLocation} immediatelly changes the location of a dockable.

\src{CLocation}s should be created using some factory methods. The first \\\src{CLocation} is obtained through the static methods of \src{CLocation}, for example \src{CLocation.base()}. Afterwards one can use the methods of the newly created object.
\begin{lstlisting}
CDockable dockable = ...
CLocation location = CLocation.base().normalSouth( 0.5 ).east( 0.5 ).stack( 2 )
dockable.setLocation( location );
\end{lstlisting}
Let's have a look at line \src{2}. First a base-location is created, indicating that \src{dockable} will be a child of the main content-area. Then \src{normalSouth( 0.5 )} tells us, that \src{dockable} will be normalized, and in the bottom half of the mainframe. The step \src{east( 0.5 )} puts \src{dockable} in the lower right quarter. And finally \src{stack( 2 )} allows \src{dockable} to be combined with other dockables that are already at that location. If there are already combined dockables at that location, then \src{dockable} will be inserted as the 3. element (counting starts at 0).

A common task is to open a dockable at the same location where another dockable is.
\begin{lstlisting}
CDockable oldDockable = ...
CDockable newDockable = ...
CLocation location = oldDockable.getLocation();
newDockable.setLocation( location );
\end{lstlisting}
This fragment will move \src{newDockable} at the location of \src{oldDockable} and put \src{oldDockable} at a new location.

It looks very strange when a dockable moves away to give space for a new dockable. Often the new dockable should just be "aside" the old one. The method \src{CLocation.aside()} provides the client with such a location.
\begin{lstlisting}
CDockable oldDockable = ...
CDockable newDockable = ...
CLocation location = oldDockable.getLocation();
newDockable.setLocation( location.aside() );
\end{lstlisting}

\subsubsection{for a group of Dockables}
Several dockables have to be registered, positioned and made visible when an application starts up. The \src{CGrid} is a class that can help doing all these things in one step. A \src{CGrid} represents a collection of dockables, where each dockable has some boundaries. The \src{CContentArea} and \src{CWorkingArea} can read the grid, take over all dockables of the grid and arrange them such that their boundaries are matched as good as possible.

An example:
\begin{lstlisting}
CControl control = ...

SingleCDockable single = new ...
MultipleCDockable multi = new ...

CGrid grid = new CGrid( control );
grid.add( 0, 0, 1, 1, single );
grid.add( 1, 0, 2, 1, multi );

control.getContentArea().deploy( grid );
\end{lstlisting}
What happens here? In lines \src{1}, \src{3} and \src{4}, new objects are created. In line \src{6} a new \src{CGrid} is created. The new grid will add all dockables to \src{control}. Then in lines \src{7} and \src{8} dockables are added to the grid. \src{single} and \src{multi} will flank each other horizontally, \src{single} on the left side, \src{multi} on the right. The size of \src{multi} will be twice the size of \src{single}. Finally in line \src{10} the contents of the grid are put onto the \src{CContentArea} of the application.

\subsubsection{Store the layout}
With "layout" are all locations and relations of the dockables meant. It's a great help for the user if he can choose between various (predefined) layouts. For example: a \LaTeX editor might have a layout for editing the document, and a layout for looking at the compiled document.

The controller allows to store the current layout, load older layouts and delete layouts during runtime. Four methods deal with the layout: \src{save}, \src{load}, \src{delete} and \src{layouts}.

The method \src{CControl.save} gives the current layout some name and stores it. The method \src{CControl.load} searches a layout with a given name and changes the location of all dockables. The method \src{delete} removes a layout, and \src{layouts} returns a \src{String[]} with the names of all currently known layouts.

\subsubsection{Store the layout persistent}
Good applications store all their properties persistent (although many developers forget the directory which the file-chooser showed last). The user should not find any changes when he closes and restarts the applications.

The controller can use an \src{ApplicationResourceManager} to store its properties. However the client is responsible to tell the controller when and where to store its properties:
\begin{lstlisting}
CControl control = ...
try{
	control.getResources().readFile(
		new File( "/home/user" ));
	control.getResources().writeFile(
		new File( "/home/user" ));
}
catch( IOException ex ){
	ex.printStackTrace();
}
\end{lstlisting}
The properties can also be stored in xml-format. But the purpose of that option is mainly for debugging and migration, most applications will do just fine using a byte-stream.

\subsubsection{Lazy initialisation}
While \src{MultipleCDockable}s are created lazy anyway, \src{SingleCDockable}s normally are created in advance. Since that can use a lot of memory, lazy initialisation for \src{SingleCDockable}s was added in version 1.0.4.

Lazy initialisation is done through a \src{SingleCDockableBackupFactory} which is added to \src{CControl}. Each backup factory represents exactly one \\\src{SingleCDockable}. If the dockable is required (for example because the layout is read from a file), the factory will create the dockable and it will be automatically added to \src{CControl}. If a \src{SingleCDockable} is removed from \src{CControl} but a backup factory still is in place, then the properties of that dockable are not deleted. If another dockable is added later to the \src{CControl} with the same unique id, then this other dockable will inherit the old properties.

\subsection{The size of dockables}
Each \src{CDockable} has a certain size. Some \src{Component}s have an optimal size, others are flexible and can have any size. There are two interesting features for the first kind of \src{Component}s.

\subsubsection{Lock size}
Every \src{CDockable} has a method \src{isResizeLockedHorizontally} and \\\src{isResizeLockedVertically}. If one of these methods returns \src{true}, then the \src{DockStation}s try not to change the size of the \src{CDockable} when the stations are resized themselfs. The user still can resize the \src{CDockable} by hand, and there are some other actions that will change the sizes as well.

Clients that use \src{DefaultSingleCDockable} and \\\src{DefaultMultipleCDockable} can use the method \src{setResizeLocked}, \\\src{setResizeLockedHorizontally} or \src{setResizeLockedVertically} to change the behavior.

\subsubsection{Request size}
Each \src{CDockable} can have a "size request" provided by \\\src{getAndClearResizeRequest}. Whenever \src{handleResizeRequest} of \src{CControl} is called, all resize requests are read and the stations try to change the size of their children such that the requests are fullfilled. There are no guarantees that the request can be fullfilled. And requests that cannot be fullfilled are simply lost.

Clients that use \src{DefaultSingleCDockable} and \\\src{DefaultMultipleCDockable} can use the method \src{setResizeRequest} to issue such a request. The method \src{setResizeRequest} can just store the request, or can process the request as well.

\subsubsection{Strategy}
Since requests can contradict each other, there needs to be a strategy how to resolve this contradictions. A \src{ConflictResolver} is used for that. Each \src{ConflictResolver} has methods to combine size-requests and thus create new requests. Additionally each \src{ConflictResolver} has methods to resolve contradictions later when the layout is applied.

Clients can use the property key \src{RESIZE_LOCK_CONFLICT_RESOLVER} (to be found in \src{CControl}) to set a new strategy. Currently there are two strategies available: \src{DefaultConflictResolver} is the default installation and tries to distribute space as fair as possible. \src{FullLockConflictResolver} denies requests of elements that are mixed with elements without requests.

\subsection{Colors associated with dockables}
Every \src{CDockable} has a map full of colors. This map, the \src{ColorMap}, is read by the \src{DockTheme}s which are included in the Common-project. If a client changes a color in the map, the change will be propagated to the graphical user interface immediatelly. There are various keys for different colors. If a client wants to change the color of a tab, it might use this piece of code:
\begin{lstlisting}
CDockable dockable = ...
ColorMap map = dockable.getColors();
map.setColor( ColorMap.COLOR_KEY_TAB_BACKGROUND, Color.RED );
\end{lstlisting}

\subsection{Preferences}
The preference system, introduced in version 1.0.6, allows the user to change the settings of this framework. The preference system is normally disabled and has to be activated by the client.

Common already has persistent storage for preferences. One can use \\\src{getPreferences} of \src{CControl} to obtain a \src{PreferenceStorage}. This storage is hooked into the \src{ApplicationResourceManager}. Whenever the manager reads or writes its content, the storage will read or write as well.

Normally an application uses exactly one \src{PreferenceModel}. \src{CControl} provides the methods \src{setPreferenceModel} and \src{getPreferenceModel} to set and access that model. The default value of this property is \src{null}. If the client sets a model, then the models content will be loaded through the storage. Afterwards the content will be distributed into the system.

The standard way how to use this property looks like this:
\begin{lstlisting}
CControl control = new CControl();
control.setPreferenceModel( new MyPreferenceModel() );

// ... further setup

control.getResources().readFile( ... );
\end{lstlisting}
The code in line \src{2} sets the model. From now on the model gets automatically loaded and stored.

Clients can use the class \src{CPreferenceModel} if they just need the default set of preferences.

Last but not least: there is a \src{MenuPiece} called \src{CPreferenceMenuPiece} which can show a dialog in which the user can modify the \src{PreferenceModel}.

\section{Menus}
Some things, like the list of all known dockables, can be presented to the user through a menu. Common uses \src{MenuPiece}s to build new menus, each \src{MenuPiece} is set of items of a \src{JMenu}. A \src{MenuPiece} can be just a child of a bigger set of items. Several \src{MenuPiece}s are put together in order to create the contents of one \src{JMenu}.

A collection of \src{MenuPiece}s:
\begin{description}
 \item[RootMenuPiece] is the root of a tree of \src{MenuPiece}s. It represents a whole \src{JMenu}. The \src{RootMenuPiece} is also a \src{NodeMenuPiece}.
 \item[NodeMenuPiece] is a list of \src{MenuPiece}s. Children can even be added or removed while the \src{JMenu} is visible.
 \item[FreeMenuPiece] can be used by the client to insert its own \src{JMenuItem}s in the menu.
 \item[SubMenuPiece] represents a whole submenu. It adds a child-\src{JMenu} into a parent-\src{JMenu}. The child menu has its own \src{RootMenuPiece}.
 \item[SeparatingMenuPiece] is a wrapper around another \src{MenuPiece}. It can add some separators above and below its child.
\end{description}

\subsection{List of dockables}
The \src{SingleCDockableListMenuPiece} contains a list of \src{JCheckBoxMenuItem}s. Each item represents one "single dockable" of a controller. When the user clicks onto one item, then the associated dockable is either made visible or invisible.

The construction of a \src{CSingleDockableListMenuPiece}:
\begin{lstlisting}
CControl control = ...
RootMenuPiece root = new RootMenuPiece( "List", false );
root.add( new SingleCDockableListMenuPiece( control ));
JMenu menu = root.getMenu();
\end{lstlisting}

\subsection{Layout}
Layout refers to the positions and relations of all the dockables. A controller can store various layouts, and a \src{CLayoutChoiceMenuPiece} allows the user to load, add or remove layouts whenever he wants to.

\subsection{List of themes}
A theme is something like a \src{LookAndFeel}. It defines the look and to some degree also the behavior of DF. There are various themes available, and the user can exchange them through a \src{CThemeMenuPiece}.

\until{1.0.5} Creating a \src{CThemeMenuPiece} has an additional effect: the theme will be stored persistent if the client stores the layouts persistent.

\since{1.0.6} The theme gets now stored automatically by the \src{ThemeMap}. Settings made in earlier versions will be lost.

\subsection{LookAndFeel}
There is a menu that exchanges the \src{LookAndFeel}, its name is \\\src{CLookAndFeelMenuPiece}.

Common uses the class \src{LookAndFeelList} to manage the \src{LookAndFeel}. This list offers a set of \src{LookAndFeel}s, and the \src{CLookAndFeelMenuPiece} is a reflection of that set. Only one \src{LookAndFeel} can be set at a time, and when changing the \src{LookAndFeel} the method \src{JComponent.updateUI()} has to be called on all \src{JComponent}s. The \src{CLookAndFeelMenuPiece} will make sure, that the \src{updateUI}-method gets called on any \src{Window} showing at least one dockable of the controller the menu is associated with. However if there are other windows, then their user interface will not get updated automatically. Then the client has to create a new \src{ComponentCollector} and add this collector to the \src{LookAndFeelList}

An example:
\begin{lstlisting}
final JDialog dialog = ...

ComponentCollector collector = new ComponentCollector(){
	public Collection<Component> listComponents(){
		List<Component> result = new ArrayList<Component>();
		result.add( dialog );
		return result;
	}
};

LookAndFeelList list = LookAndFeelList.getDefaultList();
list.addComponentCollector( collector );
\end{lstlisting}
Let's have a look at the code. In line \src{1} some dialog is defined. In lines \src{3-9} a \src{ComponentCollector} is defined. \src{collector} contains one method: \\\src{listComponents}. This method just collects some \src{Component}s, in this case \src{dialog}. For every \src{Component} found through a \src{ComponentCollector}, the \\\src{LookAndFeelList} will search the upermost parent and then update all children of this parent. That includes even child-\src{Window}s.

\subsection{Preferences}
Preferences allow the user to change the behavior of the library. The menu \src{CPreferenceMenuPiece} will insert one new item into a menu. If triggered, the item opens a dialog with the standard preferences of Common.

Clients which do not want to make any special settings should use the static method \src{setup} of \src{CPreferenceMenuPiece} to ensure that \src{CControl} actually has a \src{PreferenceModel}.

\end{document}













